This tool has only one purpose in life, to easily generate and store complex calculation formulas using the Substitute() function, which can then be pasted into a define fields dialog or a script step. The calculations are generated in an easy to read and modify format. SubstituteGen is particularly useful for long, nested substitute calculations involving a mix of text and field names. An example would be the calculation used to generate letters from a letter template. The calculations which are responsible for the creation of the XML in our ThemeMaker product were built using SubstituteGen. You can definately figure this tool out just by using it, but here's the documentation for reference's sake.
Creating a Substitution Formula
To create a new substitution formula:
1. Begin by clicking on the button labelled "New Calculation", this will create a new record in the database and put you into the "Sub Name" field. Enter a name for the calculation here. This name is only used for your reference purposes, and has no bearing on the resultant calculation.
2. In the field labelled "Original Text" enter the original text that will be operated on by the substitution calculation. This can be raw text, or the name of a field. If the original text is raw text, you will need to surround it with quotation marks.
3. Begin entering search and replace strings in the portal labelled "Search and Replace Strings". A search string is the text that the Substitute function is looking for, a replace string is what will substituted in for that text if found. Often times, you will be searching for a specified string and replacing it with a field value or vice-versa. The check boxes next to each search and replace string field specify whether or not to surround that item with quotation marks in the calculation formula that will be generated. Items which are checked will NOT be surrounded by quotes. I.E. SubstituteGen assumes that what you are entering is text strings. See below for more information on Search and Replace String entry options.
4. Once you have specified all the necessary search and replace strings that will be used in the calculation, simply click on the "Generate Sub Function" button. The complete substitute function will be generated and placed in the field labelled "Substitution Formula". Clicking into this field will select the entire contents which you can then paste into field definitions and script steps where necessary.
5. You can enter notes about the current substitution function in the field labelled "Notes".
Search and Replace String Entry
1. You can tab through the rows of the search and replace strings entering each criteria as you go. The portal allows for the creation of related records, so tabbing into the last empty row and entering a value in the field will create a new record. As you enter the check-boxes to specify whether the current item will be surrounded by quotes (remember: checked = No Quotes), you can hit the return key to select or deselect the value.
2. If you make a mistake or wish to remove a search and replace string pair, click on the trash can icon to delete that row. As in all the tools in the LitheFM Toolkit, holding the option key down while you click on the trashcan icon will suppress the dialog verifying your intention.
3. If you have exited the portal, and would like to enter a new search and replace pair without having to scroll to the bottom of the portal; click on the button labelled "New Item". This will basically take you to the last portal row and leave the cursor in the search string field.
4. As in most portals in the LitheFM Toolkit, you can sort the search and replace string portal by simply clicking on the button-like column headers. The related records will sort and the portal will display a visual highlight of which column is the sort criteria. Click on the header labelled with a "*" to unsort the portal. Note that the order of the search and replace strings in the Substitute function is based on how the portal is sorted.
5. You can use the field names of any currently open file as a value list for the search field or the replace field or both. A different file can be used for each string type, and you can turn the value lists on and off as you enter your search and replace strings. To use the list of fields from a file as a value list in the search strings, click on the check-box labelled "Use fields from file _____ as Search List". This will check the option and put the cursor into the field to select the file you would like to use from the list of currently open files. The same concept applies to the field labelled "Use fields from file _____ as Replace List". Note that if you deselect either option the file name specified remains, allowing you to easily toggle these value lists on and off as you need them.
Buttons
"New Calculation": This button creates a new record in the database, and starts you on the entry process. See "Creating a Substitution Formula" above.
"List": SubstituteGen does not have a "Find" function, instead clicking on this button will take you to a listing of all the substitution calculations in the database sorted by the name you gave them. Clicking on the row for a single record will take you back to the primary layout with that record displayed.
"New Item": Clicking on this button will take you to the last row of the search and replace string entry portal, and put the cursor in the search string field so you can enter a new pair. This keeps you from having to scroll down the the entire portal.
"Delete": This button deletes the current record and all its associated search and replace strings. Holding down the option key while you press this button will suppress the dialog verifying your intention.
"Generate Sub Function": Clicking on this button will generate a correct substitute function using every search and replace string in the entry portal. The substitution criteria will be listed in an order corresponding with the current sorting of the entry portal. Holding down the option key while you press this button will suppress the dialog asking you to confirm if you are overwriting an existing function.
(Arrow Buttons): Use the arrow buttons to move between individual substitution function records. As in all LitheFM tools, holding the option key while you press these buttons will move you to the first and last records, rather then the previous or next records.
"Hide": Just for convenience (keeps you from having to mouse up to the Window menu), pressing this button will hide the SubstituteGen window.
